Add X3M SDK and Loomit adapters to your app

X3M's Maven repository

In the project level gradle configuration file, include X3M's Maven repository:

build.gradle

allprojects {
    buildscript {
        // [...]
    }

    repositories {
        // [...]

        maven { url "https://android-artifact-registry.x3mads.com/maven" }
    }
}

build.gradle.kts

allprojects {
    buildscript {
        // [...]
    }

    repositories {
        // [...]

        maven {
            url = URI("https://android-artifact-registry.x3mads.com/maven")
        }
    }
}

XMediator Core dependency

In the app-level gradle configuration file, add the following dependency:

app/build.gradle

dependencies {
    implementation 'com.x3mads.android.xmediator:core:+'
}

app/build.gradle.kts

dependencies {
    implementation("com.x3mads.android.xmediator:core:+")
}

Add your Google Ads App Id to the Android Manifest

XMediator utilizes Google Ads services to obtain the GAID (Google Advertising ID) required by some mediation networks to serve ads.

In your app's manifest add the following metadata with your own Google Ads App ID obtained in the previus step:

app/src/main/AndroidManifest.xml

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    <application>
        <!-- [...] -->

        <meta-data
            android:name="com.google.android.gms.ads.APPLICATION_ID"
            android:value="ca-app-pub-xxxxxxxxxxxxxxxx~yyyyyyyyyy" />

    </application>
</manifest>

Choose Mediators and Networks

Use the following tool generate compatible dependencies for the Networks and Mediation SDKs of your choice.

info

If you're looking to integrate an ad network that isn't currently listed, please contact our team or your account representative to discuss support and integration options.

warning

If you are using AppLovin/MAX adapter v12.4.0 or newer through LevelPlay mediation, please be sure to remove any entry for applovin.sdk.key from your AndroidManifest.xml to avoid any compatibility issues with AppLovin's new initialization API. For more information, please visit AppLovin's documentation.

Initialize the SDK

warning

If you previously used a different mediation platform, remove any related initialization and configuration code, and ensure there is no interaction with any of its code while Loomit is active.

Before requesting any ad, make sure to call XMediatorAds.startWith() (or platform equivalent). This method configures your application Key, and fetches the required configuration parameters for the ad placements in your app, among other things.

Additionally, you may want to wait for the initialization callback to complete. This will ensure that your placement requests have the necessary prebid configurations.

---

Example (Kotlin/Java)

In addition to the example below, you can see a real implementation in our Android Demo App.

Kotlin

XMediatorAds.startWith(
    activity = activity,
    appKey = "<your-app-key>",
    initSettings = InitSettings(
        userProperties = UserProperties(
            userId = "<your-user-id>",
            customProperties = buildCustomProperties {
                addString("key1", "initialValue")
                addInt("key2", 100)
                addBoolean("key3", true)
            }
        ),
    ),
    initCallback = {
        Log.d("X3M", "Initialization complete!")
    },
)

Java

XMediatorAds.startWith(
    activity,
    "<your-app-key>",
    new InitSettings.Builder()
            .setUserProperties(new UserProperties("<your-user-id>", new CustomProperties.Builder()
                    .addString("key1", "initialValue")
                    .addInt("key2", 100)
                    .addBoolean("key3", true)
                    .build()))
            .build(),
    initResult -> {
        Log.d("X3M", "Initialization complete!")
        return Unit.INSTANCE;
    }
);

warning

To ensure the SDK is correctly configured before ad mediation begins, any method that performs an ad request will raise an exception if they are called before XMediatorAds.startWith() (or platform equivalent) is invoked.

It is mandatory to wait for the init callback to complete before making any ad request.

---

Update User Properties

After the SDK has been initialized, you can update the user properties (and custom properties) at any time. You may modify, add, or remove properties as needed.

To ensure you do not overwrite the entire configuration, always follow these steps:

1. Retrieve the current user properties.
2. Edit only the properties you want to change using the editor.
3. Pass the updated properties to setUserProperties to apply your changes.

Below you can see how to do this:

Kotlin

XMediatorAds.setUserProperties(
    XMediatorAds.getUserProperties()
        .editCustomProperties { editor ->
            // Modify key1
            editor.addString("key1", "updatedValue")
            // Remove key2
            editor.remove("key2")
            // key3 remains unchanged
            // Add new key4
            editor.addStringSet("key4", setOf("new1", "new2"))
        }
)

Java

XMediatorAds.setUserProperties(
    UserPropertiesExtensions.editCustomPropertiesOf(
        XMediatorAds.getUserProperties(),
        editor -> {
            // Modify key1
            editor.addString("key1", "updatedValue");
            // Remove key2
            editor.remove("key2");
            // key3 remains unchanged
            // Add new key4
            editor.addStringSet("key4", new HashSet<>(Arrays.asList("new1", "new2")));

        }
    )
);